home *** CD-ROM | disk | FTP | other *** search
/ Apple WWDC 1996 / WWDC96_1996 (CD).toast / Technology Materials / Newton Platform Info / Newton 2.0 Sample Code / Endpoints / protoFSM-3 / README.protoFSM < prev   
Encoding:
Text File  |  1996-03-19  |  8.3 KB  |  214 lines  |  [TEXT/R*ch]
  1. protoFSM (+ protoState + protoEvent)
  2. by Jim Schram
  3. Copyright 1996 by Apple Computer, Inc. All rights reserved
  4. Version 1.1 - March 19, 1996
  5.  
  6. protoFSM is a set of three user protos designed to make writing finite state
  7. machines much easier. To use protoFSM, you simply create a new layout in NTK
  8. and drag out a protoFSM user proto "view". Inside protoFSM, drag out protoState
  9. "views" which represent the various states of your machine. Inside each state,
  10. drag out protoEvent "views" which represent the various events each state can
  11. handle. Add viewBounds slots as necessary.
  12.  
  13. Switching to the NTK browser view of your protoFSM implementation, give each
  14. layout object a descriptive name or phrase using the "Template Info" feature of
  15. NTK. Now, add declareSelf slots containing a symbol you will use to identify
  16. each event, state, and the finite state machine itself in each of these "views."
  17.  
  18. For each event, add an Action function if the event is to perform some work. A
  19. nil action function or no function at all is acceptable (it just means this
  20. event has no work to perform). Action procedures have zero or more parameters
  21. (refer to the documentation on fsm:DoEvent(...) for more information).
  22.  
  23. For each event, add nextState slots containing the symbol of the next state the
  24. finite state machine should enter after the event's action procedure completes. 
  25. A nil nextState slot will halt the machine. No nextState slot indicates the
  26. machine should remain in the current state after the action procedure completes.
  27.  
  28. For each state which is a terminal state, add a terminal slot with the value
  29. true. A terminal state indicates the machine is in a "disposable" condition.
  30. When the finite state machine is instantiated, it is placed in the Genesis state
  31. (a required state). Genesis is a terminal state because the machine simply
  32. "exists" at this point; no clean up is required in order to dispose of the
  33. machine. You must manually add a protoState "view" with a declareSelf slot
  34. containing the value 'Genesis before your finite state machine will compile.
  35.  
  36. Lastly, add an afterScript slot to your protoFSM implementation and insert the
  37. following statement:
  38.  
  39.      call kFSMCleanUpFunc with (thisView);
  40.  
  41. This function converts the data structures created by NTK's layout editor into
  42. "pure" finite state machine structures used by protoFSM.
  43.  
  44. For more information about the use of protoFSM, refer to the Newton Technical
  45. Journal article on Finite State Machines by Bruce Thompson and Jim Schram of
  46. Newton DTS.
  47.  
  48.  
  49. ==========  Public Methods
  50.  
  51. The following methods are to be used when interacting with protoFSM. All other
  52. fields and methods are considered private and are subject to change in future
  53. implementations.
  54.  
  55. -----------
  56.  
  57. call kFSMCleanUpFunc with (thisView);
  58.  
  59. To be called in your finite state machine implementation's afterScript, this
  60. compile-time global function converts the data structures created by NTK's
  61. layout editor into the state-event structures used by the finite state machine.
  62.  
  63. -----------
  64.  
  65. fsmTemplate:Instantiate() --> fsm
  66.  
  67. Returns an instance of a finite state machine. The machine is initially in the
  68. Genesis state (a terminal state) waiting for events.
  69.  
  70. -----------
  71.  
  72. fsm:Dispose() --> nil
  73.  
  74. Release all resources in use by the finite state machine. This should only be
  75. called when the machine is in a terminal state.
  76.  
  77. -----------
  78.  
  79. fsm:DoEvent(eventSymbol, eventParametersArray) --> nil
  80.  
  81. Posts an event and an array of event action parameters to the state machine's
  82. event queue.  The calling context of this method can be any frame which
  83. inherits to the fsm instance frame.
  84.  
  85. NOTE:  The events will be processed when control returns to the main
  86. NewtonScript event loop. You may post multiple events; they will be processed
  87. in the order in which they were posted.
  88.  
  89. -----------
  90.  
  91. fsm:ExceptionHandler(exception) --> nil
  92.  
  93. The default exception handler for the state machine. Override this method to
  94. perform your own exception management for exceptions not caught by local
  95. try-onexception handlers in the event Action procedures.
  96.  
  97. -----------
  98.  
  99. fsm:?DebugFSM(reasonSymbol, stateSymbol, eventSymbol, parametersArray) --> nil
  100.  
  101. If defined, and in debug builds only, this method is called when there is an
  102. inconsistency in the state machine. The reasonSymbol parameter will contain
  103. a symbol which describes what the problem is ('UnknownEvent, 'UnknownState,
  104. 'NilState, 'NilNextState). The stateSymbol and eventSymbol parameters correspond
  105. to the state and event the machine is currently in. The parametersArray are the
  106. parameters to be passed to the event action procedure.
  107.  
  108. -----------
  109.  
  110. fsm:?TraceFSM(reasonSymbol, stateSymbol, eventSymbol, parametersArray) --> nil
  111.  
  112. If defined, and in debug builds only, this method is called as the state machine
  113. executes. The reasonSymbol parameter will contain a symbol which describes what
  114. the trace action is ('PreAction, 'PostAction, 'NextState). The stateSymbol and
  115. eventSymbol parameters correspond to the state and event the state machine is
  116. currently in, and the parametersArray are the event action procedure parameters.
  117.  
  118. -----------
  119.  
  120. fsm:IsBusy() --> nil, true
  121.  
  122. Indicates when the state machine is busy executing events (i.e. the state
  123. machine event queue is not empty).
  124.  
  125. -----------
  126.  
  127. fsm:GetSpeed() --> integer
  128.  
  129. Returns the speed at which the state machine will process events, in
  130. milliseconds.
  131.  
  132. -----------
  133.  
  134. fsm:SetSpeed(integer) --> integer
  135.  
  136. Sets the speed at which the state machine will process events, in milliseconds.
  137. Useful for debugging.  Default value is 1 (process events every millisecond).
  138.  
  139. -----------
  140.  
  141. fsm:GoToState(stateSymbol) --> nil
  142.  
  143. Forces the finite state machine to go to the stateSymbol state, and resets the
  144. event queues.
  145.  
  146. NOTE:  This function is for DEBUGGING USE ONLY. It is automatically stripped
  147. from non-debug builds.
  148.  
  149. -----------
  150.  
  151. fsm:ProtoClone(readOnlyFrame)  --> modifiableFrame
  152.  
  153. Returns a deeply modifiable frame given a read-only (or partially read-only)
  154. frame. This function is similar to DeepClone in that it iterates over each
  155. nested subframe, but instead of cloning all the slots in each nested subframe,
  156. ProtoClone creates new frames with _proto slots pointing to the subframes.
  157.  
  158. NOTE:  This function does NOT work with recursive/self-referential frames!
  159.  
  160. -----------
  161.  
  162. fsm:ObjectToString(object) --> string
  163.  
  164. Returns a string representation of object similar to SPrintObject, however,
  165. Funcs, Frames, Arrays, Booleans, Integers, & Reals are all supported.
  166.  
  167. NOTE:  This function does NOT work with recursive/self-referential frames and
  168. ignores _proto and _parent slots. The output format is valid NewtonScript
  169. syntax, except for func slots.
  170.  
  171. -----------
  172.  
  173. =============  What's New?
  174.  
  175. -----------
  176.  
  177. 1.1
  178.  
  179. Event action procedures are now called in the context of the event frame!  The
  180. event frame has _parent inheritance to the state frame. The state frame has
  181. _parent inheritance to the finite state machine instance frame. These frames
  182. are created each time the event action procedure is called, so function closures
  183. which rely on the inheritance path will always have a valid path even when the
  184. machine is in a new state.
  185.  
  186. The slots currentStateFrame and currentEventFrame can still be used during the
  187. event Action procedure to locate the current state and event frames. A new slot
  188. (fsm) is located in the finite state machine's "base" instance frame and can be
  189. used to locate the instance frame via _parent inheritance from an event Action
  190. procedure (similar to the way the base slot is used in the view system).
  191.  
  192. Some methods have been removed in order to reduce the compiled size of the
  193. machine. These methods were never documented, and were for debugging use only.
  194.  
  195. -----------
  196.  
  197. 1.0
  198.  
  199. Initial release as Newton DTS Sample Code.
  200.  
  201. -----------
  202.  
  203. No part of this document or the software described in it may be altered in any
  204. way and subsequently distributed as original material without prior written
  205. permission of Apple Computer, Inc. No licenses, express or implied, are granted
  206. with respect to any of the technology described therein. This document and the
  207. accompanying software are intended to assist application developers to develop
  208. applications only for licensed Newton platforms. Apple makes no warranty or
  209. representation either express or implied of the aforementioned technology with
  210. respect to the quality, accuracy, merchantability, or fitness for a particular
  211. purpose. As a result, this material is distributed "as is" and you, the reader,
  212. are assuming the entire risk as to its quality and accuracy. It's sample code,
  213. darn it.
  214.